TUTORIAL:

Modular robots simulation using the Open Dynamics Engine
--------------------------------------------------------

by Dr. Juan Gonzalez Gomez. (C) January, 2009

GPL License
---------------------------------------------------------
The complete tutorial can be found in this link (in Spanish):

http://www.iearobotics.com/wiki/index.php?title=Tutorial:_ODE_y_robots_modulares

but the source code is written in English. In the above link a lot of images,
screenshots and videos can be found.

More information about locomotion of limbless modular robot can be found in
my Ph.D dissertation, available at:
http://www.iearobotics.com/wiki/index.php?title=Juan_Gonzalez:Tesis
-----------------------------------------------------------

INTRODUCTION
  In this tutorial you will find 8 useful examples on how to use the 
Open Dynamics Engine (ODE). It starts by a very simple example and ends
with the simulation of an snake modular robot.

REQUIREMENTS
  The examples have been programmed using ODE version 0.9 and they have
been tested on a GNU/Linux Debian/Lenny box.

  The following packages should be installed:
  
  * libode0debian1
  * libode0-dev
  * libX11-dev
  * libgl1-mesa-dev
  
  
COMPILATION
  Just type make and all the examples will be compiled
  
------------------------------------  
EXAMPLE 1: a falling box I  (box1)
------------------------------------
This is the "hello world" program. It simulates a box that is falling because
of the gravity. A virtual world is created, the box is put inside and the
simulation is started.

  The example stores the z coordinate of the falling box at every simulation
tic and it is printed in the standard output using the octave/matlab sintax.
Therefore, the variation of the height of the box with time can be seen 
using the octave/matlab application.

  This example works in the console. No graphical 3D representation is used.
One of the advantages of the ODE is that it is independent of the 
representation. The user can choose to develop application for the console
(that do not draw the virtual world) as well as using the OpenGL or other
graphical libraries.

  The following commands should be typed to run the example:
  
  $ ./box1 > z.m
  $  octave z.m
  
  First, the simulation is executed and the standard output is sent to the 
z.m file. Then, it is shown with octave.

  A screenshot can be seen in:

http://www.iearobotics.com/wiki/images/d/dd/Tutorial_ode_box1_1.png

------------------------------------------------
EXAMPLE 2: A falling box II (box2)
------------------------------------------------
In this chapter, the previous examples is modified in order to support
collision between the objects. A ground is added. The box is located initially
at a certain height. When the simulation is started, the box begin to fall
until it reach the ground.

  There is no graphical 3D representation

This example can be execute as shown following:
 
  The following commands should be typed to run the example:
  
  $ ./box2 > z.m
  $ octave z.m

  A screenshot can be seen in:
  
  http://www.iearobotics.com/wiki/index.php?title=Imagen:Tutorial_ode_box2_1.png

When this example is execute, the following error messages appear could appear:

ODE Message 3: LCP internal error, s <= 0 (s=-0.0000e+00)

No problem. It means that there have been an internal error when performing 
some computation but the simulation is done. You can found more information 
on this following this link:

http://opende.sourceforge.net/wiki/index.php/FAQ#I_get_.22ODE_Message_3:_LCP_internal_error.2C_s_.3C.3D_0_.28s.3D0.0000e.2B00.29.22

#---------------------------------------------
EXAMPLE 3: A falling box III (box3)
#---------------------------------------------
This is the same example as 2 but the 3D graphical representation is added. It
uses the drawstuff library that is based in OpenGL. The user can see how the
box is falling and how it collides with the ground.

  Every time the user press the '1' key, the box y dropped again.

To try this example just type:

$ ./box3

Here is a screenshot:
http://www.iearobotics.com/wiki/images/7/76/Box3_screenshot1.png

and here there is a video of the simulation:
http://www.iearobotics.com/wiki/images/2/24/Tutorial_ode_box3_video.mpg

-------------------------------------
EXAMPLE 4: A compound body I (compound1)
-------------------------------------
In ODE, the simple bodies to be simulated, like the falling box, consist of a
geometry. The elementary geometries are boxes, cylinders, spheres, planes and
so on. More complex bodies can be build by using two or more geometries. They 
are called compound bodies.

  In this example a compound body consisting on two boxes is built. The body
is located at a certain height and it begins to fall when the simulation starts.
A figure showing the body can be seen here:
http://www.iearobotics.com/wiki/images/d/d9/Compound1.png

To try this example just type:
$ ./compound1

Here is a screenshot:
http://www.iearobotics.com/wiki/images/8/88/Compound1_screenshot1.png

and here is a video:
http://www.iearobotics.com/wiki/images/8/8b/Tutorial_ode_compound1_video.mpg

----------------------------------------
EXAMPLE 5: A compound body II (compound2)
----------------------------------------
In this example a compound body consisting of three geometries is built. As in
the previous example, the object is located at a certain height from the ground
and it begins to fall.

  The compound body is a prism with a triangular base. A figure can be seen
in this link along with the dimensions and the different pieces:

http://www.iearobotics.com/wiki/images/f/f5/Compound2_1.png
  
To try this example just type:
$ ./compound2

Here is a screenshot:
http://www.iearobotics.com/wiki/images/e/ec/Compound2_screenshot3.png

and here a video:
http://www.iearobotics.com/wiki/images/a/ab/Tutorial_ode_compound2_video.mpg

---------------------------------------------
EXAMPLE 6: simulation one module (servo)
---------------------------------------------
Modular robots are composed of simple modules. The aim of this example is to
build a one degree of freedom module actuated by a servo. Therefore, the 
a servo is simulated. The module consist of two bodies (boxes) connected by a
joint. The user can move the servo to three positions by pressing the '1',
'2' and '3' keys.

A picture of the module can be seen here:
http://www.iearobotics.com/wiki/images/c/c0/Module.png

To try this example just type:
$ ./servo

Here is a screenshot:
http://www.iearobotics.com/wiki/images/2/2b/Servo_screenshot1.png

and here a video:
http://www.iearobotics.com/wiki/images/b/b7/Tutorial_ode_servo_video.mpg

---------------------------------------------------------------------
EXAMPLE 7: Simulation of the locomotion of the PP configuration (PP)
---------------------------------------------------------------------
An example of the locomotion of the pitch-pitch minimal configuration.
The modular robot with the minimal number of modules that is capable of
moving in 1D is the PP minimal configuration. 

  It consist of two pitching modules. A figure can be seen here:

http://www.iearobotics.com/wiki/images/9/95/Tutorial_ode_PP.png

  For performing the locomotion, a bio-inspired controlled is used based on 
sinusoidal generators that makes the joints oscillate. A figure of the control
scheme can be found here:

http://www.iearobotics.com/wiki/images/5/55/Tutorial_ode_PP_control.png

  The equations for calculating the servo positions are written in the tutorial
page:

http://www.iearobotics.com/wiki/index.php?title=Tutorial:ODE_y_robots_modulares:Configuraci%C3%B3n_PP#Modelo_de_control

  Only two control parameters are used for moving the robot: the generators 
amplitude (A) and phase difference (PD). The values used in this example are:
A=60 degrees, PD=110 degrees.

To try this example just type:
$ ./PP

The user can move the robot forward, backward and stop it by typing the '1',
'2' and '3' keys.

Here is a screenshot:
http://www.iearobotics.com/wiki/images/f/fa/PP_screenshot3.png

Here is a video:
http://www.iearobotics.com/wiki/images/1/1a/Tutorial_ode_PP_video.mpg

---------------------------------------------------------------------
EXAMPLE 8: Simulation of a modular pitch-yaw connecting snake robot (snake)
---------------------------------------------------------------------
Modular robots are build by the union of equal modules. Depending on how the
modules are connected, there are three types of snake robots:

Pitch-pitch connecting, Yaw-yaw connecting and pitch-yaw connecting modular
robots. See the figure:
http://www.iearobotics.com/wiki/images/5/54/Snake_classification.png

In this example a 16 module pitch-yaw connecting robot is simulated. The robot
is capable of moving using 8 different gaits.

This is the geometrical model for two modules. The first one is a pitch up
and the second yawing right:
http://www.iearobotics.com/wiki/index.php?title=Imagen:Tutorial_ode_snake.png

The control model is based on sinusoidal generators. There are two groups of
them: one for controlling the vertical modules and another for the horizontal:

http://www.iearobotics.com/wiki/images/c/c4/Tutorial-ode-snake-pitch-yaw-generators.png

The relationships between the amplitude and phase differences determines the 
gait that will be performed by the robot.

To try this example just type:
$ ./snake

The user can choose the gait by pressing the corresponding key shown at the
menu.

Here is a screenshot:
http://www.iearobotics.com/wiki/images/3/3b/Snake_screenshot2.png

Here is a video:
http://www.iearobotics.com/wiki/images/a/af/Tutorial_ode_snake_video.mpg









